I suggest expanding a bit the description. Maybe something like the suggestion below:

I replaced "Plugin functions" with "WordPress functions" as I imagine those functions can be used in a theme as well, and I also included the reason why __FILE__ should not be used, plus a few other smaller changes. I'm not a native English speaker, so please feel free to improve my suggestion if something doesn't read very well.

@rodrigoprimo I updated the description as requested. As a native English speaker, your suggestion reads clear to me.

Thanks!

Maybe it is worth adding a second valid/invalid example with add_submenu_page() as this is the only function that has a different signature than the others, and where __FILE__ should not be used for the parent_slug as well as the menu_slug?

There is no need to create new <code> blocks, you can add the new example in the <code> blocks that already exist.

@rodrigoprimo Good call. I added add_submenu_page() examples to the existing code blocks with similar __FILE__ examples.

I believe it should be (missing quotes)

@rodrigoprimo You are correct, quotes are required here. Updated in my latest commit.

@jasonkenison, one final thing for consideration now that you added an example with the add_submenu_page(), maybe it is worth highlighting the first parameter of this function in the valid example, and then changing the value passed to this parameter (and highlighting it as well) to use __FILE__? This should make it clearer why an example with this function was added to the documentation (the sniff checks what is passed to both $parent_slug and $menu_slug instead of just $menu_slug as it happens with the other functions).

If you are going to include an invalid example in this parameter, I would suggest adding __FILE__ plus string concatenation or some other approach to illustrate a different case that also triggers the sniff. For example, the tests for this sniff contain __FILE__ . 'parent' (WordPress/Tests/Security/PluginMenuSlugUnitTest.inc#L9).

What do you think?

@rodrigoprimo agreed. I'll make this change.

I apologize if my original comment was unclear. What I had in mind was to keep one example with just __FILE__, and since you were going to add another example using add_submenu_page(), use it as an opportunity to show that the sniff is triggered as well when __FILE__ is concatenated with something else.

So, I would suggest reverting the change in this like to keep it as it was with just __FILE__. What do you think?

I would suggest highlighting just __FILE__ as the concatenation operator is not something that triggers the sniff.